15.8 A cleaner outline view

Some people find it noisy and distracting that the Org headlines start with a potentially large number of stars, and that text below the headlines is not indented. While this is no problem when writing a book-like document where the outline headings are really section headings, in a more list-oriented outline, indented structure is a lot cleaner:

* Top level headline             |    * Top level headline
** Second level                  |      * Second level
*** 3rd level                    |        * 3rd level
some text                        |          some text
*** 3rd level                    |        * 3rd level
more text                        |          more text
* Another top level headline     |    * Another top level headline

If you are using at least Emacs 23.2¹⁷⁴ and version 6.29 of Org, this kind of view can be achieved dynamically at display time using org-indent-mode. In this minor mode, all lines are prefixed for display with the necessary amount of space¹⁷⁵. Also headlines are prefixed with additional stars, so that the amount of indentation shifts by two¹⁷⁶ spaces per level. All headline stars but the last one are made invisible using the org-hide face¹⁷⁷; see below under ‘2.’ for more information on how this works. You can turn on org-indent-mode for all files by customizing the variable org-startup-indented, or you can turn it on for individual files using

#+STARTUP: indent

If you want a similar effect in an earlier version of Emacs and/or Org, or if you want the indentation to be hard space characters so that the plain text file looks as similar as possible to the Emacs display, Org supports you in the following way:

1. Indentation of text below headlines
   You may indent text below each headline to make the left boundary line up with the headline, like

   *** 3rd level
       more text, now indented
   

   Org supports this with paragraph filling, line wrapping, and structure editing¹⁷⁸, preserving or adapting the indentation as appropriate.

2. Hiding leading stars
   You can modify the display in such a way that all leading stars become invisible. To do this in a global way, configure the variable org-hide-leading-stars or change this on a per-file basis with

   #+STARTUP: hidestars
   #+STARTUP: showstars
   

   With hidden stars, the tree becomes:

   * Top level headline
    * Second level
     * 3rd level
     ...
   

   The leading stars are not truly replaced by whitespace, they are only fontified with the face org-hide that uses the background color as font color. If you are not using either white or black background, you may have to customize this face to get the wanted effect. Another possibility is to set this font such that the extra stars are almost invisible, for example using the color grey90 on a white background.

3. Things become cleaner still if you skip all the even levels and use only odd levels 1, 3, 5..., effectively adding two stars to go from one outline level to the next¹⁷⁹. In this way we get the outline view shown at the beginning of this section. In order to make the structure editing and export commands handle this convention correctly, configure the variable org-odd-levels-only, or set this on a per-file basis with one of the following lines:

   #+STARTUP: odd
   #+STARTUP: oddeven
   

   You can convert an Org file from single-star-per-level to the double-star-per-level convention with M-x org-convert-to-odd-levels RET in that file. The reverse operation is M-x org-convert-to-oddeven-levels.